By default kademi has two login forms:

• a small drop down login form accessed from the menu
• a login page which is displayed whenever the user attempts to access a protected resource which they cant access, either because they're not logged in or because they are but dont have access rights

Login forms

1. include theme/js/jquery.user.js in your page or template (please check for later version updates)
2. create a html form with two inputs with names email and password, and a submit button. Note that the form attributes, layout and ID attributes dont matter, its only the input names which are referenced.
3. initialise the user plugin for the form, setting appropriate values for callbacks, next url, etc

Note that initialising the user plugin isnt just for login. It also initialises javascript variables from cookies, applies user state classes to make things visible or hidden depending on whether there is a user logged in, and provides a logout function.

Step 1 - Include jquery.user.js

		<script type="text/javascript" src="/theme/js/jquery.user.js">//</script>

So far so good...

Step 2 - Create the form

Here's a simple bootstrap form:

		<form class="login form-horizontal form-horizontal-block" method="POST" role="form">
		<p class="login message" style="display: none">.</p>
		<div class="form-group">
		<label for="email" class="control-label col-md-4">Email</label>
		<div class="col-md-8">
		<input type="text"  autocapitalize="off" autocorrect="off" class="form-control" required="true" name="email" id="email" title="Email address" placeholder="Enter your email address" />
		</div>
		</div>
		<div class="form-group">
		<label for="password" class="control-label col-md-4">Password</label>
		<div class="col-md-8">
		<input type="password" class="form-control" required="true" name="password" id="password" title="Password" placeholder="Enter your password" />
		</div>
		</div>
		<div class="form-group">
		<div class="col-md-offset-4 col-md-8">
		<button type="submit" class="btn btn-sm btn-primary"><span>Login</span></button>
		<a class="Forgot" title="Forgotten password" href="/password-reset">Forgotten password</a>
		</div>
		</div>
		</form>

Step 3 - Initialise the jquery.user plugin

		<script type="text/javascript">
		$(function () {
		jQuery(".login-container").user({
		afterLoginUrl: window.location.pathname,
		valiationMessageSelector: "p.login.message"
		}); // setup login and logout
		});
		</script>

Logout

The plugin has the default logout selector of ".logout", which is configured in the logoutSelector property. Whenever a matching element is clicked the doLogout function is called:

		$(config.logoutSelector).click(function() {
		doLogout();
		});

Logging in with ajax

If you dont want to use the jquery.user plugin, you can create an ajax request to login as follows:

URL: /.dologin
Method: POST
Parameters:

The response is JSON like this. Be sure to check the status property

		{"data":{
		"name":"XXX",
		"href":"/users/XXX/public",
		"userName":"XXX",
		"userId":99999,
		"photoHash": "0f672c686fdf25f1957fca84e4b1f5c944b5cadf"},
		"fieldMessages":[],
		"messages":[],
		"nextHref":"",
		"status":true
		}

Response properties

Login template

Whenever a user attempts to access a secure resource and is not authorised the login template is rendered. The template is /theme/apps/login/login.html and you can see the default bootstrap 3.2 login template here

Since the login template is rendered in places of the actual page, bookmarks are accessible without redirects to a specific login page. To prevent caching of the login template the response is returned with 400 HTTP status code.

Recommendations on login pages and redirects

A common pattern is to redirect users away from a page when they are not authorised to access it. We recommend against this practise in Kademi.

Instead we recommend having an explicit login and/or registration process (eg on a landing page) and also have a login template which is displayed on access to a secure resource.

The advantage of a login template is that it can display an appropriate message when there is a logged in user who is being denied access, versus the situation where the user simply has not logged in. Even if you have an "all or nothing" permission strategy this is preferable because it will help you diagnose incorrect permissions. And in most cases websites evolve from all-or-nothing to have at least a few role dependent resources over time.